The Client Software Development Kits

Info
Note: The client software development kits are deprecated and will be removed in a future release.

Apama applications that are to run within the correlator can be built natively in the Apama Event Processing Language (EPL).

Although Apama includes a suite of tools to allow EPL code to be submitted to the correlator interactively, as well as submit events from text files, it is sometimes necessary to go further and integrate the correlator directly with other software, which can be achieved with these Client Software Development Kits (SDKs) using C++, Java or .NET. Note that connectivity plug-ins often provide a simpler approach than the SDKs. The following SDK layers are available:

  • Engine Management API. Low-level base API on which other APIs are built. It provides facilities to inject/delete EPL, send/receive events, inspect and monitor engines. See Engine Management API for detailed information.

    Note: In most cases, we recommend using one of the higher-level APIs listed below in preference to the Engine Management API.

  • Engine Client API. More powerful API built on top of the Engine Management API. It provides all the functionality provided by the Engine Management API along with functionality such as auto-reconnection or listeners for property changes. See Engine Client API for detailed information.

  • Event Service API. More powerful API focused around sending and receiving events to and from channels. It provides synchronous or asynchronous pseudo-RPC mechanisms. See Event Service API for detailed information.

  • Scenario Service API. Provides an external interface to DataViews. See Scenario Service API for detailed information.

The Engine Management API is available for C++, Java and .NET. The other APIs are available only for Java and .NET.

The client libraries

The client libraries can be found in the following locations of your Apama installation:

  • For C++, in the lib directory: libapclient.so (-lapclient) on UNIX, or apclient.lib on Windows.
  • For Java, in the lib directory: ap-client.jar.
  • For .NET, in the bin directory: apclientdotnet.dll (and its dependency apclient.dll).

Using the C++ client library

To program against the C++ SDK, you must use the definitions from the engine_client_cpp.hpp header file, which is located in the include directory of your Apama installation.

C++ compilers vary extensively in their support for the ISO C++ standard and in how they support linking. For this reason, Apama supports only specific C++ compilers and development environments. For a list of the supported C++ compilers, see Supported Platforms.

To configure the build for an Apama C++ client:

  • On UNIX, copying and customizing an Apama makefile from a sample application is the easiest method.

  • On Windows, you might find it easiest to copy an Apama sample project. If you prefer to use a project you already have, be sure to add $(APAMA_HOME)\include as an include directory. To do this in Visual Studio, select your project and then select Project Properties > C++ > General > Additional Include Directories.

    Also, link against apclient.lib. To do this in Visual Studio, select your project and then select Project Properties > Linker > Input > Additional Dependencies and add apclient.lib.

    Finally, select Project Properties > Linker > General > Additional Library Directories and add $(APAMA_HOME)\lib.

Using the Java client library

Add the ap-client.jar library to your classpath when compiling and running.

Using the .NET client library

To make use of the .NET wrapper, add the apclientdonet.dll library as a reference of your assembly.

To run an application using the wrapper:

  1. Copy the following libraries from the bin directory of your Apama installation into the directory that contains your compiled .NET assembly:
    • apclient.dll
    • apclientdonet.dll
    • log4net.dll
  2. Ensure that the bin directory of your Apama installation is in the PATH environment variable.

Working with event objects

To create event objects to use with the Client Software Development Kits (and also to delete them), use the following:

  • For C++, use com::apama::event::createEvent and related functions.
  • For Java, use com.apama.event.parser.EventType and its associated classes.
  • For .NET, use Apama.Event.Parser.EventType and its associated classes.

Logging

Logging in C++

The C++ API can output extensive information. This information can be useful in diagnosing connectivity issues or problems that you may encounter when writing the software that interfaces with the engine. As an author of a C++ client, you need not bother with the standard logging unless you want to modify its operating parameters.

By default, the log level is set to WARN, where only significant warnings and errors are displayed in the log. The whole list of log levels is OFF (that is, no logging at all), CRIT, FATAL, ERROR, WARN, INFO, DEBUG and TRACE. These levels are listed in order of decreasing importance, and conversely in the order of least likely occurrence. A very large volume of information is output at DEBUG level.

To change the logging, the C++ API provides various functions which can be found in the header file (.hpp). These functions generally have the term “log” in their names.

Logging in Java and .NET

The logging facilities in Java and .NET are significantly more powerful than in C++. The Java API makes use of Log4j, a publicly available logging library for Java. For your convenience, Apama provides a wrapper class that abstracts the logging capabilities provided, and it is this interface that is used by the Client API for Java. See the Javadoc of the com.apama.util.Logger class for more information about the logging facility.

The .NET API makes use of log4net, a publicly available logging library for .NET. For your convenience, Apama provides a wrapper class that abstracts the logging capabilities provided, and it is this interface that is used by the Client API for .NET. See the documentation of the Apama.Util.Logger class for more information about the logging facility.

Exception handling and Thread Safety

Exception handling

Several of the methods and functions of the API can throw exceptions if they fail or encounter exceptional circumstances. All of these are of the following type:

  • com::apama::EngineException in C++
  • com.apama.EngineException in Java
  • Apama.EngineException in .NET

An exception contains a text message indicating the nature of the problem encountered.

Thread safety

All client APIs are thread-safe, unless otherwise specified, in the sense that you can call API methods from any thread. Several background threads are created during the usage of a client API. Events received from a correlator will be handled in one of background threads, so you cannot assume that events will be delivered to you on any particular thread.